/*
 * Copyright 2002-2011 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.xml;

import org.w3c.dom.Element;

import org.springframework.beans.factory.config.BeanDefinition;
import org.springframework.lang.Nullable;

/**
 * Interface used by the {@link DefaultBeanDefinitionDocumentReader} to handle custom,
 * top-level (directly under {@code <beans/>}) tags.
 *
 * <p>Implementations are free to turn the metadata in the custom tag into as many
 * {@link BeanDefinition BeanDefinitions} as required.
 *
 * <p>The parser locates a {@link BeanDefinitionParser} from the associated
 * {@link NamespaceHandler} for the namespace in which the custom tag resides.
 *
 * @author Rob Harrop
 * @since 2.0
 * @see NamespaceHandler
 * @see AbstractBeanDefinitionParser
 */

/**
 作用： 自定义命名空间中的具体解析器实现
2方法
 BeanDefinition parse(Element element, ParserContext parserContext)
 参数:
	 Element element: 需要被解析成一个或多个Bean定义的XML元素
	 ParserContext parserContext: 封装了解析过程当前状态的对象，提供了对BeanDefinitionRegistry的访问
3 实现类
	 AbstractBeanDefinitionParser: 抽象基类实现，提供通用的解析逻辑
	 AbstractSingleBeanDefinitionParser: 继承自AbstractBeanDefinitionParser，专门用于解析生成单个Bean定义的场景
	 具体的解析器实现，如:
	 SimplePropertyNamespaceHandler
	 UtilNamespaceHandler中的各种解析器
4 和其他接口和类之间的关系
	 与 NamespaceHandler 关系: BeanDefinitionParser 通过 NamespaceHandler 进行定位和管理，每个自定义命名空间都需要对应的 NamespaceHandler 来提供 BeanDefinitionParser 实现
	 与 DefaultBeanDefinitionDocumentReader 关系: 该类使用 BeanDefinitionParser 来处理自定义的顶级标签
	 与 BeanDefinition 关系: BeanDefinitionParser 的主要职责就是将XML元素解析为一个或多个 BeanDefinition 实例
	 与 ParserContext 关系: 解析过程中通过 ParserContext 获取注册表和其他上下文信息
5 总结
 BeanDefinitionParser 是Spring框架中用于XML配置解析的重要接口，它的主要职责是：
	 处理自定义XML标签
	 将XML元素转换为Bean定义
	 与Spring的命名空间处理机制紧密集成
	 提供灵活的扩展点，允许开发者处理自定义的XML配置元素
	 该接口体现了Spring框架高度可扩展的设计理念，通过这种机制，开发者可以扩展Spring的XML配置语法，添加自定义的配置元素。
6 应用场景
 自定义命名空间: 当需要扩展Spring XML配置语法时，开发者可以创建自己的命名空间，并提供相应的 BeanDefinitionParser 实现
 简化复杂配置: 通过自定义标签简化复杂Bean的配置过程
 集成第三方框架: 在与第三方框架集成时，可以提供更友好的XML配置方式
 领域特定语言(DSL): 创建面向特定领域的配置语法，提高配置的可读性和易用性
 例如，Spring的AOP、事务管理、JDBC等模块都使用了这种机制来提供简洁的XML配置语法。
 */
public interface BeanDefinitionParser {

	/**
	 * Parse the specified {@link Element} and register the resulting
	 * {@link BeanDefinition BeanDefinition(s)} with the
	 * {@link org.springframework.beans.factory.xml.ParserContext#getRegistry() BeanDefinitionRegistry}
	 * embedded in the supplied {@link ParserContext}.
	 * <p>Implementations must return the primary {@link BeanDefinition} that results
	 * from the parse if they will ever be used in a nested fashion (for example as
	 * an inner tag in a {@code <property/>} tag). Implementations may return
	 * {@code null} if they will <strong>not</strong> be used in a nested fashion.
	 * @param element the element that is to be parsed into one or more {@link BeanDefinition BeanDefinitions}
	 * @param parserContext the object encapsulating the current state of the parsing process;
	 * provides access to a {@link org.springframework.beans.factory.support.BeanDefinitionRegistry}
	 * @return the primary {@link BeanDefinition}
	 */
	@Nullable
	BeanDefinition parse(Element element, ParserContext parserContext);

}
